@alfacapital-tech/c4builder 0.3.0 → 0.4.0-rc.2

package/README.MD

@@ -94,6 +94,29 @@ Options:
 There is also a `jre` subcommand: `c4builder jre install [--force]` pre-downloads the
 private JRE cache, `c4builder jre info` prints which Java would be used.
 
+### Validating single diagrams
+
+`c4builder check <file...>` validates individual `.puml` / `.iuml` / `.d2` files with the
+same engines the build uses (bundled PlantUML jar + system/managed Java, bundled D2) —
+no project or `.c4builder` needed, nothing is written. Handy for pre-commit hooks and CI:
+exit code 0 when every file compiles, 1 otherwise; errors are printed as
+`✗ file: line N: <engine message>`.
+
+```bash
+c4builder check src/c4/context.puml lib/shared.iuml diagrams/flow.d2
+```
+
+`!include` paths resolve relative to the checked file's directory; a `.iuml` library is
+validated by including it into an empty diagram.
+
+A minimal pre-commit hook (`.git/hooks/pre-commit`) that validates staged diagrams:
+
+```bash
+#!/bin/sh
+files=$(git diff --cached --name-only --diff-filter=ACM -- '*.puml' '*.iuml' '*.d2')
+[ -z "$files" ] || exec c4builder check $files
+```
+
 By default, running `c4builder` will attempt to build the project.
 
 If no configuration was set it will ask for it and then do the actual build. Running just `c4builder` after a configuration will no longer show the wizard.
@@ -263,6 +286,124 @@ By default this is disabled. If enabled, the output will no longer include the a
 
 The current entity structure is inserted after the header
 
+## Plugins
+
+Plugins extend the build with content from outside `rootFolder` (virtual pages that go through
+the regular pipeline: sidebar, search, `generateMD`, complete markdown, local diagram render)
+and with site assets. They are listed in `.c4builder` under `plugins` — either `"name"` or
+`["name", { ...options }]`:
+
+```json
+{
+  "plugins": [
+    "openspec",
+    ["openapi", { "dir": "../contracts", "glob": "*/openapi.yaml" }]
+  ]
+}
+```
+
+A plugin identifier resolves in this order: a built-in name (`openspec`, `openapi`) → a local
+ESM module (`./plugins/my.mjs`, `../shared/plugin.mjs`, absolute path) → an npm package resolved
+from the project directory. Options are validated by the plugin's own zod schema **before** the
+build starts (built-in plugins are strict — an unknown option key is an error); `${ENV_VAR}`
+placeholders inside string options are replaced from the environment (unset → empty string) and
+never printed (archive URLs appear in messages without their query string, so a token passed as
+`?private_token=${TOKEN}` stays out of the logs). A malformed `plugins` entry always fails the
+build (it is the one key the wizard cannot repair). Older c4builder versions ignore the `plugins`
+key, so a rollback keeps building.
+
+### `openspec` — publish a local OpenSpec store
+
+Renders an [OpenSpec](https://github.com/Fission-AI/OpenSpec) store as a site section:
+a summary (counters, task progress), a page per active change, the specs tree and the archive.
+A change page shows the header (schema, dates, task progress, links to subpages) plus the first
+artifact of `artifacts` (by default `proposal` — the "why" is visible without a click); the
+remaining artifacts (`design`, `tasks`, then any other `*.md` alphabetically) are subpages, and
+spec deltas live under `specs/…` mirroring the folder layout (a folder that has its own
+`spec.md` and nested specs gets one page: the spec followed by the list of nested ones).
+```` ```plantuml ```` / ```` ```d2 ```` fences inside artifacts, deltas and store specs are
+rendered by the **local** engines (nothing is sent to plantuml.com); the image name is derived
+from the fence content, so inserting or reordering fences never reuses a neighbour's cached
+image. Relative links between artifacts of a change point to their pages, referenced files
+(images, notes) are copied next to the page (and to the output root for the complete markdown;
+`excludeOtherFiles` applies). The store folder is watched in `-w`.
+
+| Option      | Default                        | Meaning                                                        |
+|-------------|--------------------------------|----------------------------------------------------------------|
+| `dir`       | `openspec`                     | store folder (relative to the project directory)               |
+| `mount`     | `OpenSpec`                     | section name (and its path in the output folder)               |
+| `artifacts` | `["proposal","design","tasks"]`| artifact order; the first one is shown on the change page itself |
+
+### `openapi` — swagger-ui pages for a set of OpenAPI specs
+
+Finds specs by `glob` in a local folder (`dir`) **or** in a `tar.gz`/`zip` archive fetched over
+HTTP (`archive`, e.g. a GitLab/GitHub repository archive URL; `subdir` picks a folder inside it,
+`headers` adds request headers such as `{"PRIVATE-TOKEN": "${GITLAB_TOKEN}"}` — empty values are
+dropped, so the same config works with and without a token). One page per spec, named after the
+spec's parent folder (file name for specs in the source root), plus an index. All `yaml`/`yml`/
+`json` files of the source are copied into `<mount>/_specs/…` keeping their relative layout, so
+relative `$ref`s (including shared schema files that do not match `glob`) keep resolving; pages
+load swagger-ui from the bundled `vendor/` files — no CDN, no access to the source repository is
+needed by readers. The plugin forces `executeScript` (logged) and injects `swagger-ui.css` and
+`swagger-ui-bundle.js` into `index.html` after the template is rendered (skipped when the template
+already links the bundle), so custom `docsifyTemplate`s need no change. The output folder is never
+treated as a source (`dir: "."` is fine). Archives are downloaded once per process (watch mode
+reuses them).
+
+| Option    | Default                          | Meaning                                  |
+|-----------|----------------------------------|------------------------------------------|
+| `mount`   | `API`                            | section name                             |
+| `dir`     | —                                | local folder with specs (watched in `-w`)|
+| `archive` | —                                | HTTP(S) URL of a tar.gz/zip archive      |
+| `subdir`  | —                                | folder inside the archive / `dir`        |
+| `headers` | —                                | HTTP headers for the archive request     |
+| `glob`    | `**/openapi.{yaml,yml,json}`     | spec pattern (`**`, `*`, `?`, `{a,b}`)   |
+
+Example for a repository that keeps its `openspec/` store next to the C4 sources and consumes
+contracts from another repository:
+
+```json
+{
+  "plugins": [
+    "openspec",
+    ["openapi", {
+      "archive": "https://gitlab.example.com/api/v4/projects/123/repository/archive.tar.gz?sha=main",
+      "glob": "*/openapi.yaml",
+      "headers": { "PRIVATE-TOKEN": "${GITLAB_TOKEN}" }
+    }]
+  ]
+}
+```
+
+### Writing a plugin
+
+A plugin is an ESM module whose default export is a plain object (use `definePlugin` from
+`@alfacapital-tech/c4builder/dist/core/plugins/types.js` for typing):
+
+```js
+import { z } from 'zod';
+export default {
+  name: 'changelog',
+  options: z.object({ file: z.string().default('CHANGELOG.md') }).strict(), // optional
+  watchPaths: (opts) => [opts.file],                                          // optional
+  assets: { styles: ['/abs/path/x.css'], scripts: ['/abs/path/x.js'] },      // optional
+  requires: { executeScript: true },                                          // optional
+  async afterScan(ctx, opts) {
+    // ctx.tree, ctx.options — the build tree/options; ctx.source({ dir } | { archive, subdir, headers })
+    // resolves a folder; ctx.addPage adds a virtual page (missing parents become index pages).
+    ctx.addPage({
+      path: ['Changelog'],
+      markdown: '## Latest\n\n![flow](flow.puml)',
+      diagrams: [{ file: 'flow.puml', content: '@startuml\nA -> B\n@enduml' }]
+    });
+  },
+  async afterBuild(ctx, opts) { /* ctx.distFolder, ctx.options — copy extra files, run checks */ }
+};
+```
+
+Hooks run in the order of the `plugins` list; an exception aborts the build with the plugin's
+name (the previous `dist` backup is kept as usual).
+
 # Future plans
 
 I would like to bind the **build** phase to the C4 model. It could parse the diagrams and know what Person/System/Component/Container is related to what and help with additional validation. Maybe even export to [structurizr](https://structurizr.com/) or vice versa.
@@ -305,19 +446,24 @@ Use the image directly in CI (GitHub Actions, GitLab CI) as the job image — th
 Publishing is triggered by pushing a git tag `v<version>` — pushes/merges to `master` alone
 do not publish.
 
-**Release candidate** (from `refactor/phoenix`, no merge to `master` needed):
+Every user-facing PR adds a line to the `## Unreleased` section of the change log below;
+the release commit renames it to `## vX.Y.Z`.
+
+**Release candidate** (from `master`, as many as needed — consumers pinned to `rc`
+pick each one up automatically):
 
 ```
-npm version 0.3.0-rc.1 -m "rc: %s"
+npm version X.Y.Z-rc.1 -m "rc: %s"      # first candidate
+npm version prerelease -m "rc: %s"      # next ones: rc.2, rc.3, …
 git push --follow-tags
 ```
 
-Publishes to dist-tag `rc`.
+Publishes to npm dist-tag `rc` and docker tag `rc`; `latest` is untouched.
 
-**Final release:**
+**Final release** (rename `## Unreleased` → `## vX.Y.Z` first):
 
 ```
-npm version 0.3.0 -m "release: %s"
+npm version X.Y.Z -m "release: %s"
 git push --follow-tags
 ```
 
@@ -325,6 +471,22 @@ Publishes to dist-tag `latest`.
 
 # Change log
 
+## Unreleased
+
+- Plugin system: `plugins` key in `.c4builder`, `afterScan`/`afterBuild` hooks, virtual pages,
+  plugin assets injected into `index.html`, `dir`/`archive` source resolver (see «Plugins»)
+- Built-in plugins: `openspec` (local OpenSpec store → site section, local diagram render) and
+  `openapi` (offline swagger-ui pages for a set of OpenAPI specs; `vendor/swagger-ui/swagger-ui.css` 5.32.1)
+- `c4builder check <file...>` — validate individual `.puml` / `.iuml` / `.d2` files with the
+  bundled engines, without a project build (#13)
+- D2 compile errors are printed as readable `file:line:col: message` lines instead of raw JSON
+- Regression test for two adjacent `![..](x.puml)` embeds (#12 — the bug itself was fixed in 0.3.0)
+- Diagram cache key now includes the output path: diagrams that swap contents (or fence blocks
+  that shift position) are re-rendered instead of silently reusing a neighbour's cached image.
+  The first build after upgrading re-renders everything once.
+- Watch mode ignores the output folder, its backup and `.c4builder*`, and de-duplicates nested
+  watch roots (a plugin `dir` covering the project no longer loops the rebuild)
+
 ## v0.3.0
 
 Full TypeScript rewrite (ESM, Node.js ≥ 20.19) with the same CLI and `.c4builder` format.

package/dist/cli/commands/check.js

@@ -0,0 +1,80 @@
+import chalk from 'chalk';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { VENDOR_DIR } from "../../util/paths.js";
+import { VENDORED_JAR } from "../../util/utils.js";
+import { resolveJava } from "../../core/render/jre.js";
+import { renderDiagram } from "../../core/render/diagrams.js";
+import { renderD2, teardownD2 } from "../../core/render/d2renderer.js";
+// `c4builder check <file...>` — валидация отдельных диаграмм ТЕМ ЖЕ движком, что и
+// сборка (вендорный PlantUML jar + системная/managed java, бандл D2), без проекта и
+// `.c4builder`. Рендер идёт в память и выбрасывается: проверяем ровно то, что упало бы
+// в сборке (системный `plantuml` может отличаться версией). Код выхода 0 — все файлы ок,
+// 1 — есть ошибка (движка, неизвестного расширения или чтения файла).
+// stderr PlantUML в -pipe: `ERROR` / позиция / описание. Позиция — 0-based строка
+// диаграммы, для файла с одной диаграммой это file:N+1.
+// ponytail: в файле с несколькими @startuml позиция считается от начала блока — смещение
+// не учитываем, добавить, если такие файлы станут проверять.
+const PUML_ERROR = /^ERROR\n(\d+)\n(.*)$/m;
+const JAR_PATH = path.join(VENDOR_DIR, VENDORED_JAR.jar);
+// JRE резолвится лениво и один раз: список только из .d2 java не трогает.
+let javaPromise = null;
+const getJava = () => {
+    javaPromise ??= resolveJava({ log: (m) => console.log(chalk.gray(m)) }).then((r) => r.path);
+    return javaPromise;
+};
+const checkPlantUml = async (abs) => {
+    // .iuml — библиотека без @startuml: сам по себе PlantUML «рендерит» его без ошибок,
+    // поэтому проверяем через включение в пустую диаграмму.
+    const isLib = path.extname(abs) === '.iuml';
+    const content = isLib ? `@startuml\n!include ${abs}\n@enduml\n` : await readFile(abs);
+    const isDitaa = /@startditaa/i.test(content.toString());
+    try {
+        await renderDiagram(content, {
+            javaBin: await getJava(),
+            jarPath: JAR_PATH,
+            includePath: path.dirname(abs),
+            format: isDitaa ? 'png' : 'svg',
+            charset: 'UTF-8',
+            isDitaa,
+            useSystemFonts: false
+        });
+    }
+    catch (e) {
+        const m = e.message.match(PUML_ERROR);
+        if (!m)
+            throw e;
+        // Для .iuml позиция относится к обёртке, а не к файлу — не показываем.
+        throw new Error(isLib ? m[2] : `строка ${Number(m[1]) + 1}: ${m[2]}`);
+    }
+};
+const CHECKERS = {
+    '.puml': checkPlantUml,
+    '.iuml': checkPlantUml,
+    '.d2': (abs) => renderD2(abs)
+};
+export default async (files) => {
+    if (files.length === 0) {
+        console.log(chalk.red('использование: c4builder check <file...>  (.puml | .iuml | .d2)'));
+        process.exit(1);
+    }
+    let failed = 0;
+    // ponytail: последовательно — на сотнях файлов добавить пул как в generateImages.
+    for (const file of files) {
+        const abs = path.resolve(file);
+        const check = CHECKERS[path.extname(abs).toLowerCase()];
+        try {
+            if (!check)
+                throw new Error('неизвестное расширение (ожидается .puml, .iuml или .d2)');
+            await check(abs);
+            console.log(chalk.green(`✓ ${file}`));
+        }
+        catch (e) {
+            failed++;
+            console.error(chalk.red(`✗ ${file}: ${e.message}`));
+        }
+    }
+    await teardownD2();
+    if (failed)
+        process.exit(1);
+};

package/dist/cli/commands/help.js

@@ -36,6 +36,10 @@ ${chalk.cyan('Replace diagrams with a link')}
 Replaces the diagram images with links.
 ${chalk.cyan('Include breadcrumbs')}
 Shows the original folder hierarchy after each title.
+${chalk.cyan('Plugins')} (${chalk.gray('.c4builder → "plugins", no wizard prompt')})
+List of build plugins: "name" or ["name", { options }]. Built-in: openspec (local OpenSpec store →
+site section), openapi (swagger-ui pages for OpenAPI specs from a folder or an HTTP archive).
+See README «Plugins».
 ${chalk.cyan('Place diagrams before text')}
 Choose to place diagrams before or after the text.
 ${chalk.cyan('Exclude other files')}

package/dist/cli/commands/list.js

@@ -73,6 +73,9 @@ Charset: ${currentConfiguration.CHARSET !== undefined
 Exclude other files: ${currentConfiguration.EXCLUDE_OTHER_FILES !== undefined
         ? chalk.green(currentConfiguration.EXCLUDE_OTHER_FILES)
         : chalk.red('not set')}
+Plugins: ${currentConfiguration.PLUGINS?.length
+        ? chalk.green(currentConfiguration.PLUGINS.map((p) => (typeof p === 'string' ? p : p[0])).join(', '))
+        : chalk.gray('none')}
 `);
     // Битые ключи показаны выше как «not set» (щадящий разбор их выбросил); помечаем их
     // сырым значением и причиной, чтобы было видно, что и почему требует правки/визарда.

package/dist/cli/dispatch.js

@@ -6,10 +6,13 @@ import Configstore from 'configstore';
 import cmdHelp from "./commands/help.js";
 import cmdNewProject from "./commands/new.js";
 import cmdJre from "./commands/jre.js";
+import cmdCheck from "./commands/check.js";
 import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
 import cmdCollect from "./wizard/collect.js";
 import { build } from "../core/build.js";
+import { loadPlugins, pluginWatchPaths } from "../core/plugins/load.js";
+import fs from 'node:fs';
 import watch from 'node-watch';
 import { EventEmitter } from 'node:events';
 import { clearConsole } from "../util/utils.js";
@@ -19,7 +22,7 @@ import { acquireBuildLock, BuildLockHeldError } from "../util/lock.js";
 // больше не будет (одиночный запуск).
 import { teardownD2 } from "../core/render/d2renderer.js";
 import { packageJson as pkg } from "../util/paths.js";
-import { parseConfig } from "../config/options.js";
+import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
@@ -93,7 +96,8 @@ function getOptions(c) {
         SUPPORT_SEARCH: c.supportSearch,
         EXECUTE_SCRIPT: c.executeScript,
         EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
-        USE_SYSTEM_FONTS: c.useSystemFonts
+        USE_SYSTEM_FONTS: c.useSystemFonts,
+        PLUGINS: c.plugins
     };
 }
 export default async () => {
@@ -118,19 +122,22 @@ export default async () => {
             throw new InvalidArgumentError('ожидается TCP-порт: целое число 1..65535');
         return Number(v);
     })
-        .allowExcessArguments() // позиционные аргументы подкоманды `jre <action>`
+        .allowExcessArguments() // позиционные аргументы подкоманд `jre <action>` и `check <file...>`
         .parse(process.argv);
     const opts = program.opts();
     // Прогрев JRE — до загрузки конфига проекта и intro: команда самостоятельна.
     if (program.args[0] === 'jre')
         return cmdJre(program.args.slice(1), { force: opts.force });
+    // Проверка отдельных диаграмм — тоже без конфига проекта.
+    if (program.args[0] === 'check')
+        return cmdCheck(program.args.slice(1));
     let conf = { get: () => { } };
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
     // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.
     let lockPath = '';
+    const configPath = path.join(process.cwd(), opts.configFile ?? '.c4builder');
     if (!opts.new) {
         const projectKey = process.cwd().split(path.sep).splice(1).join('_');
-        const configPath = path.join(process.cwd(), opts.configFile ?? '.c4builder');
         lockPath = `${configPath}.lock`;
         conf = new Configstore(projectKey, {}, { configPath });
         cacheConf = new Configstore(`${projectKey}_cache`, {}, { configPath: `${configPath}.cache` });
@@ -174,9 +181,11 @@ export default async () => {
     // Повторная сборка установленного проекта (есть HAS_RUN, не --config) — строгий путь:
     // битый конфиг обязан упасть с внятной ошибкой сразу, а не быть тихо «починен» визардом.
     // Первый запуск (!HAS_RUN) и --config остаются щадящими — это штатный путь восстановления.
+    // `plugins` визард не спрашивает — salvage молча переписал бы его в `[]` и сборка
+    // прошла бы без раздела плагина; битый `plugins` роняет всегда.
     const strictBuild = !opts.config && !!currentConfig.HAS_RUN;
     if (configIssues.length) {
-        if (strictBuild)
+        if (strictBuild || configIssues.some((i) => i.key === 'plugins'))
             failOnConfigIssues(configIssues);
         warnConfigIssues(configIssues);
         // Битые ключи чиним физически (salvage-значение = дефолт схемы, либо удаление):
@@ -206,13 +215,30 @@ export default async () => {
         const options = getOptions(built.value);
         if (opts.systemFonts)
             options.USE_SYSTEM_FONTS = true; // флаг сильнее ключа конфига
+        // Плагины грузятся и валидируются до первой сборки: битые опции — exit 1 сразу.
+        const plugins = await loadPlugins(options.PLUGINS, process.cwd(), options).catch((e) => {
+            console.error(chalk.red(`Ошибка загрузки плагинов: ${e.message}`));
+            return process.exit(1);
+        });
         const reloadEmitter = new EventEmitter();
         reloadEmitter.setMaxListeners(0);
         if (opts.watch) {
             // node-watch: CJS-рантайм при ESM-.d.ts (export default) — дефолт-импорт
             // типизируется как namespace. Каст к реальной сигнатуре, рантайм не меняется.
             const watchDir = watch;
-            watchDir(options.ROOT_FOLDER, { recursive: true }, async (_evt, name) => {
+            const inside = (p, dir) => p === dir || p.startsWith(dir + path.sep);
+            // Пути наблюдения — абсолютные и без вложенных друг в друга: node-watch дедуплицирует
+            // события по имени, а один файл под двумя корнями приходил бы дважды.
+            const candidates = [
+                path.resolve(options.ROOT_FOLDER),
+                ...pluginWatchPaths(plugins, process.cwd(), fs.existsSync)
+            ];
+            const watchPaths = candidates.filter((p, i) => !candidates.some((q, j) => j !== i && inside(p, q) && (p !== q || j < i)));
+            // Собственные записи сборки (dist, dist_bk, .c4builder*) не должны триггерить
+            // ребилд — при dir плагина, накрывающем cwd, это бесконечная петля.
+            const output = outputDirs(options);
+            const filter = (name, skip) => output.some((d) => inside(name, d)) || name.startsWith(configPath) ? skip : true;
+            watchDir(watchPaths, { recursive: true, filter }, async (_evt, name) => {
                 // clearConsole();
                 // intro();
                 console.log(chalk.gray(`\n${name} changed. Rebuilding...`));
@@ -229,10 +255,10 @@ export default async () => {
                     // каталоге не потопчет dist_bk и не потеряет чексуммы кеша.
                     const release = acquireBuildLock(lockPath);
                     try {
-                        await build(options, cacheConf);
+                        await build(options, cacheConf, plugins);
                         while (attemptedWatchBuild) {
                             attemptedWatchBuild = false;
-                            await build(options, cacheConf);
+                            await build(options, cacheConf, plugins);
                         }
                     }
                     finally {
@@ -269,7 +295,7 @@ export default async () => {
             process.exit(1);
         }
         try {
-            await build(options, cacheConf);
+            await build(options, cacheConf, plugins);
         }
         finally {
             release();

package/dist/config/options.js

@@ -4,7 +4,13 @@
 // Форма файла `.c4builder` (camelCase) — единый тип задаёт zod-схема (config/schema),
 // её же валидацией опирается загрузка опций сборки. Ре-экспорт: потребители типа
 // (defaults, dispatch) продолжают импортировать его отсюда.
+import path from 'node:path';
 import { configSchema } from "./schema.js";
+/** Один невалидный ключ `.c4builder`: имя ключа верхнего уровня, его сырое значение и причина. */
+/** Суффикс бэкапа выходного каталога на время сборки (`docs` → `docs_bk`). */
+export const DIST_BACKUP_FOLDER_SUFFIX = '_bk';
+/** Выходные каталоги сборки (абсолютные): dist и его бэкап — их нельзя ни сканировать, ни наблюдать. */
+export const outputDirs = (options) => [options.DIST_FOLDER, options.DIST_FOLDER + DIST_BACKUP_FOLDER_SUFFIX].map((d) => path.resolve(d));
 /**
  * Разбирает сырой объект `.c4builder`, разделяя строгий и щадящий пути. Сам НЕ печатает
  * и НЕ завершает процесс — решение (ошибка+выход либо предупреждение) принимает CLI.

package/dist/config/schema.js

@@ -61,6 +61,14 @@ export const configSchema = z.object({
     // путей не валит сборку) — runtime дальше работает с чистым string[].
     excludeSidebarFolderByPath: nullish(z.preprocess((v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : v), z.array(z.string()).optional())),
     hasRun: optBool(),
+    // Плагины сборки: `"имя"` либо `["имя", {опции}]`. Опции здесь не валидируются —
+    // это делает схема самого плагина при загрузке (core/plugins/load); верхний уровень
+    // проверяет лишь форму записи, чтобы ошибка называла `plugins` и позицию.
+    plugins: nullish(z
+        .array(z.union([z.string(), z.tuple([z.string(), z.record(z.string(), z.unknown())])], {
+        error: 'ожидается "имя" либо ["имя", {опции}]'
+    }))
+        .default([])),
     // Легаси-ключи старых `.c4builder` — читаются лишь для однократного предупреждения.
     plantumlVersion: optStr(),
     generatePDF: optBool(),

package/dist/core/build.js

@@ -5,14 +5,18 @@ import { makeDirectory, writeOnSameLine } from "../util/utils.js";
 // clearD2FileCache: сброс кеша графа D2-импортов на границах сборки (сам webworker
 // D2 гасит CLI после одиночной сборки — в watch-режиме он переживает ребилды).
 import { clearD2FileCache } from "./render/d2renderer.js";
+import { DIST_BACKUP_FOLDER_SUFFIX } from "../config/options.js";
 // Фазы сборки: scan (дерево исходников) → render (диаграммы) → compose (markdown/сайт).
 import { generateTree, engineSupportsRemote, clearIncludeCache } from "./scan/tree.js";
 import { generateImages } from "./render/diagrams.js";
 import { generateMD, generateWebMD, generateCompleteMD, clearDiagramCache } from "./compose/markdown.js";
+// Плагины: хуки afterScan (виртуальные страницы) / afterBuild и ассеты сайта.
+// Загружены заранее в cli/dispatch и приходят третьим аргументом (как cacheConf).
+import { runAfterScan, runAfterBuild } from "./plugins/hooks.js";
+import { injectPluginAssets } from "./plugins/assets.js";
 // Оркестратор владеет lifecycle выходного каталога: dist бэкапится в dist_bk, откуда
 // generateImages восстанавливает неизменённые по чексумме картинки; в конце бэкап сносится.
-const DIST_BACKUP_FOLDER_SUFFIX = '_bk';
-const build = async (options, cacheConf) => {
+const build = async (options, cacheConf, plugins = []) => {
     const start_date = new Date();
     const bkFolderName = options.DIST_FOLDER + DIST_BACKUP_FOLDER_SUFFIX;
     // Generating local images, remove old backup image folder, rename current dist folder to new backup
@@ -38,6 +42,9 @@ const build = async (options, cacheConf) => {
         console.log(chalk.green(`\nbuilding documentation in ./${options.DIST_FOLDER}`));
         const tree = await generateTree(options.ROOT_FOLDER, options);
         console.log(chalk.blue(`parsed ${tree.length} folders`));
+        // Виртуальные страницы плагинов встают в дерево до рендера — дальше они
+        // неотличимы от реальных папок (диаграммы, sidebar, поиск, complete).
+        await runAfterScan(tree, options, plugins);
         // У движков без онлайн-рендера (D2, см. remoteRender в DIAGRAM_ENGINES) при
         // выключенной локальной генерации диаграммы не во что превратить — ссылки на
         // SVG вели бы в никуда. Падаем сразу с понятной ошибкой, а не молча битым выводом.
@@ -66,6 +73,7 @@ const build = async (options, cacheConf) => {
         if (options.GENERATE_WEBSITE) {
             console.log(chalk.blue('generating docsify site'));
             await generateWebMD(tree, options);
+            await injectPluginAssets(plugins, options);
         }
         if (options.GENERATE_COMPLETE_MD_FILE) {
             console.log(chalk.blue('generating complete markdown file'));
@@ -78,6 +86,7 @@ const build = async (options, cacheConf) => {
             console.log(chalk.bold(chalk.yellow('WARNING:')));
             console.log(chalk.yellow(`PDF-вывод больше не поддерживается. Удалите вручную из .c4builder: ${options.LEGACY_PDF_KEYS.join(', ')}.`));
         }
+        await runAfterBuild(options, plugins);
         console.log(chalk.green(`built in ${(Date.now() - start_date.getTime()) / 1000} seconds`));
         ok = true;
     }

package/dist/core/plugins/assets.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { encodeURIPath } from "../../util/utils.js";
+// Вставка тегов в готовый HTML: стили — перед последним `</head>`, скрипты — перед
+// последним `</body>` (регистронезависимо); тега нет — в конец файла (браузер исполнит
+// и так). Пост-обработка не зависит от того, чей это шаблон (docsifyTemplate пользователя
+// править не требуется). Экспортируется для юнит-теста.
+export const injectHtml = (html, { styles, scripts }) => {
+    const before = (doc, closing, block) => {
+        if (!block)
+            return doc;
+        const m = [...doc.matchAll(closing)].pop();
+        return m?.index === undefined
+            ? `${doc}\n${block}`
+            : `${doc.slice(0, m.index)}${block}\n${doc.slice(m.index)}`;
+    };
+    const styleTags = styles.map((s) => `<link rel="stylesheet" href="${s}">`).join('\n');
+    const scriptTags = scripts.map((s) => `<script src="${s}"></script>`).join('\n');
+    return before(before(html, /<\/head>/gi, styleTags), /<\/body>/gi, scriptTags);
+};
+/**
+ * Копирует ассеты плагинов в `dist/vendor/plugins/<name>/` и подключает их в
+ * `dist/index.html`. Зовётся после generateWebMD (index.html уже записан).
+ */
+export const injectPluginAssets = async (plugins, options) => {
+    const indexPath = path.join(options.DIST_FOLDER, 'index.html');
+    const html = fs.readFileSync(indexPath, 'utf8');
+    // Файл с тем же именем уже подключён шаблоном (дефолтный шаблон сам грузит
+    // vendor/swagger-ui-bundle.js) — второй раз не копируем и не подключаем.
+    const linked = (file) => new RegExp(`(?:src|href)=["'][^"']*\\b${path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`).test(html);
+    const styles = [];
+    const scripts = [];
+    for (const { plugin } of plugins) {
+        if (!plugin.assets)
+            continue;
+        const rel = path.posix.join('vendor', 'plugins', plugin.name);
+        const destDir = path.join(options.DIST_FOLDER, 'vendor', 'plugins', plugin.name);
+        const copy = (files, out) => {
+            for (const file of files ?? []) {
+                if (linked(file))
+                    continue;
+                fs.mkdirSync(destDir, { recursive: true });
+                fs.copyFileSync(file, path.join(destDir, path.basename(file)));
+                out.push(encodeURIPath(path.posix.join(rel, path.basename(file))));
+            }
+        };
+        copy(plugin.assets.styles, styles);
+        copy(plugin.assets.scripts, scripts);
+    }
+    if (!styles.length && !scripts.length)
+        return;
+    fs.writeFileSync(indexPath, injectHtml(html, { styles, scripts }));
+};

package/dist/core/plugins/hooks.js

@@ -0,0 +1,30 @@
+import { resolveSource } from "./source.js";
+import { addPage } from "./tree.js";
+const wrap = async (name, hook, fn) => {
+    try {
+        await fn();
+    }
+    catch (e) {
+        throw new Error(`Плагин ${name} (${hook}): ${e.message ?? e}`, { cause: e });
+    }
+};
+export const runAfterScan = async (tree, options, plugins) => {
+    for (const { plugin, opts } of plugins) {
+        if (!plugin.afterScan)
+            continue;
+        const ctx = {
+            tree,
+            options,
+            addPage: (page) => addPage(tree, options, page),
+            source: resolveSource
+        };
+        await wrap(plugin.name, 'afterScan', () => plugin.afterScan?.(ctx, opts));
+    }
+};
+export const runAfterBuild = async (options, plugins) => {
+    for (const { plugin, opts } of plugins) {
+        if (!plugin.afterBuild)
+            continue;
+        await wrap(plugin.name, 'afterBuild', () => plugin.afterBuild?.({ distFolder: options.DIST_FOLDER, options }, opts));
+    }
+};